home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok22.lha / Lists / Lists.dok < prev    next >
Text File  |  1993-08-15  |  7KB  |  212 lines

  1. ======================================================================
  2. Dokumentation zu "Lists" Version 2.0
  3. Autor: Nicolas Benezan, Postwiesenstr. 2, D7000 Stuttgart 60
  4. ======================================================================
  5.  
  6. Kopierrecht
  7. ­­­­­­­­­­­
  8. Das komplette Packet (Quelltext, Dokumentation und Objectcode) ist
  9. Public Domain Software. Es darf beliebig kopiert und verbreitet werden
  10. solange...
  11.  
  12. * mein Name und dieser Kopierrechtshinweis erhalten bleiben,
  13. * die Vollständigkeit des ganzen Packets gewährleistet ist, und
  14. * mit dem Vertrieb dieser Software kein Gewinn erwirtschaftet wird.
  15.  
  16. Die Kommerzielle Nutzung ohne meine ausdrückliche schriftliche
  17. Genehmigung ist untersagt.
  18. Ferner ist allen Personen, die in irgend einer Weise etwas mit "Data
  19. Becker" zu tun haben, insbesondere für "Data Becker" arbeiten oder
  20. deren Produkte verkaufen, jegliche Verwendung dieser Software verboten.
  21.  
  22. Verbesserungsvorschläge sind stets willkommen. Falls Sie Veränderungen
  23. am Programm vornehmen, dokumentieren Sie diese bitte gut verständlich.
  24. Es würde mich freuen, wenn Sie mich über größere Veränderungen in
  25. Kenntnis setzen würden.
  26.  
  27. (c) 1988 by Nicolas Benezan.
  28.  
  29.  
  30. Übersicht
  31. ­­­­­­­­­
  32. * Umfang des Packets
  33. * Einleitung
  34. * Beschreibung der Prozeduren
  35. * Weitere generische Datentypen
  36.  
  37.  
  38. Umfang des Packet
  39. ­­­­­­­­­­­­­­­­­
  40. Das komplette Packet "Lists" beinhaltet folgendes:
  41.  
  42. * Lists.dok          Diese Dokumentation
  43. * Lists.doc          Englische Dokumentation
  44. * Lists.def          Definitionsmodul
  45. * Lists.mod          Implementationsmodul
  46. * Lists.sym          Symboldatei (compiliertes Definitionsodul)
  47. * Lists.obj          Objektcode (compiliertes Implementationsmodul)
  48. * TestLists.mod      Testmodul für Lists
  49. * TestLists.obj      Objektcode
  50. * TestLists          Ausführbares Testmodul
  51.  
  52.  
  53. Einleitung
  54. ­­­­­­­­­­
  55. Falls Sie mit dem Prinzip der generischen Datentypen noch nicht vertraut
  56. sind, empfielt es sich, die Dokumentationen von [1]-[4] durchzulesen.
  57. Dieses Modul stellt den generischen Datentyp "List" zur Verfügung. Es ist
  58. eine komplett neue Version des auf Amok#7 befindlichen List-Moduls und
  59. bietet wesentlich umfangreichere Operationen.
  60. Da die Listen jetzt vorwärts und rückwärts verzeigert sind, ist es nun
  61. möglich, gezielt auf bestimmte Einträge absolut oder relativ zu
  62. positionieren, anstatt die Liste immer nur von Anfang an durchzugehen.
  63. Durch den exportierten Typ EntryPtr kann man sich auch bestimmte Stellen in
  64. der Liste "merken" und zwischen diesen hin und her springen.
  65. Die Operationen ReadEntry, AppendEntry, InsertEntry und ReplaceEntry
  66. existieren jeweils in zwei Versionen: eine mit Kopieren der Daten und eine,
  67. die nur mit Zeigern arbeitet. Es ist so zum Beispiel möglich, eine Liste
  68. schnell nach einem Datenfeld zu durchsuchen, ohne die gesammten Daten in
  69. lokale Variablen kopieren zu müssen. (Allerdings wird dies mit einer
  70. höheren bug-anfälligkeit erkauft. Seien Sie vorsichtig mit dem Umgang der
  71. nicht kopierenden Prozeduren!)
  72.  
  73.  
  74. Beschreibung der Prozeduren
  75. ­­­­­­­­­­­­­­­­­­­­­­­­­­­
  76. Auf den Datentyp "List" können folgende Operationen ausgeführt werden:
  77.  
  78. CreateList()
  79. ------------
  80. Erzeugt eine neue, leere Liste. Vor dieser Operation darf auf eine
  81. Liste nicht zugegriffen werden.
  82.  
  83. AppendEntry()
  84. -------------
  85. Fügt einen Eintrag an das Ende der Liste an. Dabei werden die Daten
  86. nicht kopiert, sondern nur ein Knoten mit einem Zeiger auf die Daten
  87. an die Liste angehängt. Man muß hier aufpassen, daß man auf keinen Fall
  88. lokale Variablen verwendet, oder den Speicher der Daten Dealloziert,
  89. bevor man den Eintrag wieder aus der Liste entfernt hat. Man sollte die
  90. Daten auch nicht (unbeabsichtigt) verändern bzw. deren Speicher wieder-
  91. verwenden.
  92.  
  93. AppendEntryC()
  94. --------------
  95. Wie zuvor, kopiert jedoch die Daten in einen neu allozierten Speicher-
  96. bereich. Somit dürfen hier auch lokale Variablen für den Paramenter "Data"
  97. verwendet werden.
  98.  
  99. RemoveEntry()
  100. -------------
  101. Dies ist das Gegenstück zu AppendEntry() oder InsertEntry(). Es entfernt
  102. einen Eintrag aus der Liste, ohne seinen Datenbereich zu deallozieren.
  103.  
  104. DeleteEntry()
  105. -------------
  106. Ist das Gegenstück zu AppendEntryC() oder InsertEntryC(). Es entfernt
  107. einen Eintrag aus der Liste und aus dem Speicher.
  108.  
  109. DeleteList()
  110. ------------
  111. Löscht eine komplette Liste mitsamt ihren Einträgen. Vorsicht: alle
  112. noch vorhandenen Einträge werden dealloziert, was zu Problemen führen
  113. kann, wenn Sie die nicht kopierenden AppendEntry()- oder InsertEntry()-
  114. Prozeduren verwendet haben.
  115.  
  116. InsertEntry()
  117. -------------
  118. Fügt einen neuen Eintrag in eine Liste ein. Entgegen Exec.Insert()
  119. wird vor der angegebenen Position eingefügt, d.h. wenn an der
  120. Stelle des Eintrags 5 eingefügt wird, so wird der neue Eintrag
  121. die neue Nr. 5, die alte Nr. 5 wird die neue Nr. 6 usw.
  122.  
  123. InsertEntryC()
  124. --------------
  125. Wie zuvor, Kopiert jedoch die Daten in einen neu allozierten Speicher-
  126. bereich.
  127.  
  128. ReadEntry()
  129. -----------
  130. Gibt Adresse und Größe der Daten eines Eintrags zurück. Die Daten
  131. werden nicht kopiert.
  132.  
  133. ReadEntryC()
  134. ------------
  135. Wie zuvor, kopiert die Daten jedoch in einen VAR-Parameter.
  136.  
  137. ReplaceEntry()
  138. --------------
  139. Ersetzt das Datenfeld eines Eintrags durch ein neues. Hierbei wird
  140. kein Speicher (de-)alloziert sondern nur die Zeiger umgestellt.
  141.  
  142. ReplaceEntryC()
  143. ---------------
  144. Überschreibt ein Datenfeld eines Eintrags mit neuen Daten, d.h. kopiert
  145. die Übergebenen Daten in den alten Speicherbereich.
  146.  
  147. ListOk()
  148. --------
  149. Gibt an, ob die Operationen seit dem letzten Aufruf von ListOk()
  150. erfolgreich waren, oder ob kein Speicher mehr frei war oder sonst
  151. ein Fehler aufgetreten ist. Im Definitionsmodul steht eine Liste
  152. aller möglichen Fehlerursachen.
  153.  
  154. EntriesInList()
  155. ---------------
  156. Gibt an, wieviele einträge eine Liste hat.
  157.  
  158. LocateEntryAbs()
  159. ----------------
  160. Gibt einen EntryPtr auf einen Eintrag mit der angegebenen Nummer
  161. zurück. Für den ersten und Letzten Eintrag existieren besondere
  162. Prozeduren (siehe unten).
  163.  
  164. LocateEntryRel()
  165. ----------------
  166. Positioniert auf den Eintrag, der sich um einen bestimmten Offset
  167. vor (negativ) oder hinter (positiv) dem angegebenen Eintrag befindet.
  168. Für den direkten Vorgänger oder Nachfolger existieren besondere
  169. Prozeduren (siehe unten).
  170.  
  171. FirstEntry()
  172. ------------
  173. Gibt einen EntryPtr auf den ersten Eintrag zurück (Vorsicht: die Liste
  174. darf nicht leer sein).
  175.  
  176. LastEntry()
  177. ------------
  178. Gibt einen EntryPtr auf den letzten Eintrag zurück (Vorsicht: die Liste
  179. darf nicht leer sein).
  180.  
  181. Successor()
  182. -----------
  183. Positioniert auf den Nachfolger eines Eintrags (sofern vorhanden).
  184.  
  185. Predecessor()
  186. -------------
  187. Positioniert auf den Vorgänger eines Eintrags (sofern vorhanden).
  188.  
  189. ListAllocProc, ListDeallocProc
  190. ------------------------------
  191. Mit diesen Prozedurvariablen können Prozeduren installiert werden, die
  192. von Lists für das Allozieren/Deallozieren von Speicher verwendet werden.
  193. Voreingestellt sind die aus TaskMemory.
  194.  
  195. Unterstützung von Strings
  196. -------------------------
  197. Die einzelnen Einträge einer Liste dürfen unterschiedliche Länge haben,
  198. wodurch variable Strings unterstützt werden.
  199. Darüberhinaus wird beim Kopieren eines kürzeren in ein längeres Datenfeld
  200. automatisch ein Nullbyte angehängt. Umgekehrt werden überstehende Zeichen
  201. abgetrennt.
  202.  
  203.  
  204. Weitere generische Datentypen
  205. ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­
  206. [1] Amok#7:List
  207. [2] Amok#7:Queue
  208. [3] Amok#7:Stack
  209. [4] Amok#7:AVL
  210. [5] Amok#13:Rows
  211.  
  212.